💡 Motivation and Context

The flags service can answer with a typed record (PostHog/posthog#107732), selected by /flags?v=4 (PostHog/posthog#123366). Clients already send v=3 and arbitrary v values, so only an exact v=4 selects the new record. A v4 record carries one typed value (boolean, string, number, object or null) instead of enabled and variant, plus a structured reason and rule metadata.

This PR moves the SDK to that response and keeps the full record for each flag, while every existing getter and event returns the same values as before for valid flag records. It adds no new public methods and does not change event emission. The typed accessor API (get_boolean_value / _details and the string, number, integer, float and object forms) is split out into #1147, which stacks on this PR and waits for the cross-SDK accessor spec in PostHog/sdk-specs#104.

The reader follows the wire contract published in posthog-sdk-test-harness 1.22.0 (contracts/feature_flag_rules_v2, contract 7.0.0):

1. Both clients request /flags/?v=4. A record with value is a v4 record. A record without it comes from a server that does not serve v4, which answers v=4 with the older record. Its value is variant, or enabled when there is no variant, its config version is 1, and any rule context in it is ignored. No probing or retry. Each client logs one diagnostic (at info level) the first time it reads such a response. There is deliberately no retry with v=2: the flags service answers a v it does not serve with an older record rather than an error, so a fallback request would only repeat requests that failed for other reasons (an outage, a quota limit), doubling their load and hiding the error.
2. Unknown fields are ignored. A known field with the wrong JSON type makes that record unreadable, in either record shape; other flags in the response are unaffected. A key member of the wrong type is such a field; a string key that differs from the map key is ignored, and the map key stays the flag key. An unreadable record:
   • is not stored in the flag fallback cache, so a value cached from an earlier good response is still served;
   • reads as disabled when nothing is cached;
   • makes a single-flag getter report what 7.82.1 reported when the response failed: $feature_flag_error: "unknown_error", with no request ID or evaluated-at. So a stale cached value is told apart from a fresh one.
3. The legacy rendering is derived from value in one place, when the record is parsed: a boolean as is, a string as the variant, null as false, and a number or object as true with the value as its payload. v4 sends metadata.payload: null for number and object flags, so the SDK supplies the payload from the value (the same JSON value, not necessarily the same text), and ignores a payload a record sends with a number or object value. Payloads for boolean and string values are kept as sent. get_feature_flag, get_feature_flag_result, get_feature_flag_payload, get_all_flags(_and_payloads), the snapshot getters, $feature/<key>, $active_feature_flags and $feature_flag_called return the same values for both responses.
4. Each remotely evaluated flag in an evaluate_flags() snapshot keeps its parsed record internally (typed value, failure state, reason and metadata), for the follow-up accessors. The snapshot keeps one copy per flag and decodes payloads only when they are read.

Notes for reviewers

• The parsed FeatureFlag keeps the typed value and failure state in private attributes (_value, _failed, _malformed_field), and FlagMetadata keeps the v4 rule metadata in private attributes (_config_version, _rule_type, _rule_id, _variant_key, _forced_variant). They are instance attributes with class-level defaults, not dataclass fields, so repr, equality, hashing, dataclasses.asdict() and the generated SDK reference show only the existing fields (a test pins this). They are private on purpose: get_flags_decision() returns these types, so public fields could be adopted before the typed flag API settles. feat(flags): typed flag value accessors #1147 makes them public together with the typed accessors. No new public fields, types, exports or methods are added. FlagMetadata.id and FlagMetadata.version are now None when a record has none, instead of 0; events already left a falsy ID and version out, so event properties do not change.
• FeatureFlag.from_json(), FlagMetadata.from_json() and FlagReason.from_json() build the subclass they are called on, as in 7.82.1.
• The supplied payload for number and object values is compact JSON in wire key order. Decoded payloads are identical to v=2; only float exponent spelling can differ (1e-07 here, 1e-7 from the server).
• Compatibility, beyond the reason text below: FlagMetadata.id and FlagMetadata.version widen from int to Optional[int] (absent stays None instead of 0), and a record with a known field of the wrong JSON type, such as a string reason, an empty-string reason or a non-boolean has_experiment, now reads as described in point 2. Before, such a record was read anyway or failed the whole response. A value nested too deeply to encode also fails only its own record. When nothing is cached, two results for the unreadable flag itself differ from 7.82.1, where the whole response failed: a single-flag getter returns False instead of None, and a snapshot read of it sends its event without flag_missing. Its sibling flags now read normally instead of failing with it.
• For flags in the new format, the server writes different reasons at v4 than at v2: both reason.description ("Matched rule 2" instead of "Matched condition set 2") and reason.code (no_rule_match instead of no_condition_match). FeatureFlagResult.reason and $feature_flag_reason show the v4 text once a server sends v4. Values do not change, and v1 flags are identical in every field.
• FlagMetadata keeps no experiment_id or holdout_id. Contract 7.0.0 lets only config version 1 records carry metadata.experiment_id, so the reader checks that it is an integer (a wrong type fails the record) and does not keep it.
• Memory, for an evaluate_flags() snapshot of 5,000 flags: 2.87 MiB without payloads (7.82.1: 1.50 MiB) and 7.95 MiB with 1 KiB payloads (7.82.1: 20.9 MiB). The extra cost without payloads is the parsed record each flag keeps.
• The SDK compliance adapter declares the flags_response_v4 capability, and CI runs harness 1.23.0, which checks flags_request_uses_v4_query_param instead of the ?v=2 check.
• The flags service already serves v4, so this can be released once it is approved. The changeset is minor.

💚 How did you test it?

• posthog/test/test_flags_released_behaviour.py compares this SDK with results recorded by posthog 7.82.1. posthog/test/released_flags_scenarios.py uses only the public client API, so the same scenarios run on 7.82.1 (which recorded posthog/test/fixtures/released_flags_7_82_1.json; the module says how to regenerate it) and on this SDK, from both the v2 and the v4 response shapes. They cover every legacy getter, get_flags_decision, the snapshot getters, capture(flags=...), capture(send_feature_flags=True), every $feature_flag_called event, responses with an unreadable record, and fallback cache histories (good, then unreadable, then a timeout or error). The only expected differences are the absent ID and version and the unreadable flag's own value, and the test says which decision causes each one.
• posthog/test/test_flags_v4_response.py (153 tests), built on fixtures copied unchanged from harness release 1.22.0. posthog/test/fixtures/feature_flag_rules_v2/SOURCE.json records the release, revision and file digests, and a test checks them. It covers:
  • all valid producer responses, retained field by field;
  • older-server records, and the sync and async clients logging once per client;
  • wrongly typed known fields in both record shapes, records that are not objects, sibling isolation and unknown fields; failed records never render their value;
  • unreadable records with and without a cached value;
  • absent flag IDs and versions, and number or object values sent with a conflicting payload;
  • from_json() on subclasses;
  • legacy parity: the v1 legacy projection corpus and the typed value corpus render the same legacy values from a v2-shaped and a v4-shaped record.
• Full suite (6,009 passed; the fork-based metrics tests are deselected locally because they crash on macOS with and without this change), ruff format --check, ruff check, mypy with the baseline filter, and the public API snapshot check.
• Ran the compliance suite locally against harness 1.23.0, with the adapter in capture v0 and v1 modes: 56/56 and 121/121 passed, including flags_request_uses_v4_query_param.

📝 Checklist

• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

If releasing new changes

• Ran sampo add to generate a changeset file

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Written by Claude Code, an AI agent, from a brief by the assignee. The agent extended the existing parsing path rather than adding a parallel one: the parsed FeatureFlag carries the typed value, and the legacy fields are derived from it once. An earlier revision moved the typed accessor API to #1147, so this change ships without new public methods. A later review round kept unreadable records out of the fallback cache, kept the unknown_error 7.82.1 reported for them, built from_json() subclasses again, reduced snapshot memory, and pinned legacy results to a 7.82.1 recording instead of comparing the new SDK with itself. Choices the reviewer may want to revisit are listed under "Notes for reviewers".

🤖 Generated with Claude Code